Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

Using Custom Tags

Custom tags are user-defined JSP language elements that encapsulate recurring tasks. Custom tags are distributed in a tag library, which defines a set of related custom tags and contains the objects that implement the tags.

Custom tags have the syntax

<prefix:tag attr1="value" ... attrN="value" />  

or

<prefix:tag attr1="value" ... attrN="value" > 
  body
</prefix:tag> 

where prefix distinguishes tags for a library, tag is the tag identifier, and attr1 ... attrN are attributes that modify the behavior of the tag.

To use a custom tag in a JSP page, you must:

See Chapter 12 for detailed information on the different types of tags and how to implement tags.

Declaring Tag Libraries

You declare that a JSP page will use tags defined in a tag library by including a taglib directive in the page before any custom tag from that tag library is used.

<%@ taglib prefix="tt" [tagdir=/WEB-INF/tags/dir | uri=URI ] %> 

The prefix attribute defines the prefix that distinguishes tags defined by a given tag library from those provided by other tag libraries.

If the tag library is defined with tag files (see Encapsulating Reusable Content using Tag Files), you supply the tagdir attribute to identify the location of the files. The value of the attribute must start with /WEB-INF/tags/ and a translation error will occur if the value points to a directory that doesn't exist or if used in conjunction with the uri attribute.

The uri attribute refers to a URI that uniquely identifies the tag library descriptor (TLD), a document that describes the tag library (See Tag Library Descriptors).

Tag library descriptor file names must have the extension .tld. TLD files are stored in the WEB-INF directory or subdirectory of the WAR file or in the META-INF/ directory or subdirectory of a tag library packaged in a JAR. You can reference a TLD directly or indirectly.

The following taglib directive directly references a TLD filename:

<%@ taglib prefix="tlt" uri="/WEB-INF/iterator.tld"%> 

This taglib directive uses a short logical name to indirectly reference the TLD:

<%@ taglib prefix="tlt" uri="/tlt"%> 

The iterator example defines and uses a simple iteration tag. The JSP pages use a logical name to reference the TLD. A sample iterator.war is provided in <INSTALL>/j2eetutorial14/examples/web/provided-wars/. To build and package the example:

  1. In a terminal window, go to <INSTALL>/j2eetutorial14/examples/web/iterator/.
  2. Run asant build. This target will spawn any necessary compilations and copy files to the <INSTALL>/j2eetutorial14/examples/web/iterator/build/ directory.
  3. Start the J2EE server.
  4. Start deploytool.
  5. Create a Web application called iterator by running the New Web Application Wizard. Select FileRight ArrowNewRight ArrowWeb Application WAR.
  6. New Web Application Wizard
    1. Select the Create New Stand-Alone WAR Module radio button.
    2. Click Browse.
    3. In the file chooser, navigate to <INSTALL>/docs/tutorial/examples/web/iterator/.
    4. In the File Name field, enter iterator.
    5. Click Choose Module File.
    6. In the WAR Display Name field, enter iterator.
    7. In the Context Root field, enter /iterator.
    8. Click Edit. In the Edit Contents dialog, navigate to <INSTALL>/docs/tutorial/examples/web/iterator/build/. Select the index.jsp and list.jsp JSP pages and iterator.tld and click Add. Notice that iterator.tld is put into /WEB-INF/.
    9. Click Next.
    10. Select the JSP radio button.
    11. Click Next.
    12. Select index.jsp from the JSP file combo box.
    13. Click Finish.

You map a logical name to an absolute location in the Web application deployment descriptor. To specify the mapping of the logical name /tlt to the absolute location /WEB-INF/iterator.tld with deploytool:

  1. Select the File Refs tab.
  2. Click the Add button in the JSP Tag Libraries tab.
  3. Enter the relative URI /tlt in the Coded Reference field.
  4. Enter the absolute location /WEB-INF/iterator.tld in the Tag Library field.

You can also reference a TLD in a taglib directive with an absolute URI. For example, the absolute URIs for the JSTL library are:

When you reference a tag library with an an absolute URI that exactly matches the URI declared in the taglib element of the TLD (see Tag Library Descriptors), you do not have to add the taglib element to web.xml; the JSP container automatically locates the TLD inside the JSTL library implementation.

Including the Tag Library Implementation

In addition to declaring the tag library, you also need to make the tag library implementation available to the Web application. There are several ways to do this. Tag library implementations can be included in a WAR in an unpacked format: tag files are packaged in the /WEB-INF/tag/ directory and tag handler classes are packaged in the /WEB-INF/classes/ directory of the WAR. Tag libraries already packaged into a JAR file are included in the /WEB-INF/lib/ directory of the WAR. Finally, an application server may load a tag library into all the Web applications running on the server. For example, in the J2EE 1.4 Application Server, the JSTL TLDs and libraries are distributed in the archive appserv-jstl.jar in <J2EE_HOME>/lib/. This library is automatically loaded into the classpath of all Web applications running on the J2EE application server so you don't need to add it to your Web application.

To package the iterator tag library implementation in the /WEB-INF/classes/ directory and deploy the iterator example with deploytool:

  1. Select the General tab.
  2. Click Edit.
  3. Add the iterator tag library classes.
    1. In the Edit Contents dialog, navigate to <INSTALL>/docs/tutorial/examples/web/iterator/build/.
    2. Select the iterator and myorg packages and click Add. Notice that the tag library implementation classes are packaged into /WEB-INF/classes/.
  4. Click OK.
  5. Select FileRight ArrowSave.
  6. Deploy the application.
    1. Select ToolsRight ArrowDeploy.
    2. In the Connection Settings frame, enter the user name and password you specified when you installed the J2EE 1.4 Application Server.
    3. Click OK.
    4. A popup dialog will display the results of the deployment. Click Close.

To run the iterator application, open the URL http://localhost:1024/iterator in a browser.

Divider
Download
FAQ
History
HomeHomeNext API
Search
Feedback
Divider

All of the material in The J2EE 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.